SSM AutomationにおけるRunCommand実行ステップの「document worker timed out」エラーを解消した話

#AWS Systems Manager Automation

眞鍋賢司

2024.10.07

 はじめにAWS Systems Manager (SSM) Automationを利用して、EC2インスタンス上でPowerShellスクリプトを実行する際、稀に「document worker timed out」というエラーが発生するケースに直面しました。
本記事では、実際に行った調査や原因分析、対処方法について解説し、最終的にエラー解消に至るまでのアプローチをご紹介します。
 エラーの詳細エラーが発生したステップでは下記のPowerShellコマンドを実行しています。
# メタデータから自身のインスタンスIDを取得
$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
$instance_id = (Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/instance-id)

# ホスト名をEC2のタグに設定
New-EC2Tag -Resource $instance_id -Tag @{Key = "ComputerName"; Value = $Env:COMPUTERNAME}
エラーとなった際のステップの実行結果をコンソール上で確認すると、下記のメッセージが出力されていました。
document process failed unexpectedly: document worker timed out
また、SSMエージェントのログも確認しましたが、上記エラーメッセージ以外には参考になるログは見つかりませんでした。
 エラー原因の調査エラーメッセージから原因の特定ができず、正常終了する場合と異常終了する場合の差分も見つからなかったため、実機で検証することにしました。
まず、エラーが発生したEC2インスタンス上で問題のコマンドを手動実行し、システムリソースの使用状況を観察しました。

結果として、「New-EC2Tag」コマンド実行時にメモリ使用率が急増し、処理の完了に約30秒を要することが判明しました。
この挙動から、一時的なメモリ不足によって、SSM Automationのタイムアウトが引き起こされていると推測しました。
 解決策と実装メモリの消費を抑え、安定した実行を可能にするため、SSM Automationの手順を見直しました。
 変更前と変更後の処理フロー変更前
EC2インスタンス上で直接ホスト名をタグに設定する「New-EC2Tag」コマンドを実行する

変更後
EC2インスタンス上ではホスト名取得のみを行い、ランブック内の変数として保持する。後続のステップで、AWS APIを使用してタグ付けを行う。

上記の修正後、無事タイムアウトエラーは発生しなくなりました。

結果から、一時的なメモリ不足が原因だったことが確認できました。
 さいごに今回の問題解決を通じて、AWSのリソース管理やAutomationの設計に関する知識が深まりました。

今後はこの経験を基に、よりシンプルで信頼性のある実装を目指していきたいと思います。